You can ignore the mypy issue. It should be fixed by jaraco/jaraco.text#28

Here's additional non-deprecated, non-historical documentations that assume a still active pkg_resources:

https://github.com/pypa/setuptools/blob/main/docs/setuptools.rst#transitional-note

such as needing to import all namespace
packages during the initialization of the pkg_resources runtime, and also
the need for pkg_resources to be explicitly imported before any namespace
packages work at all.

This entire section could be moved to your new blurb about transitioning.

https://github.com/pypa/setuptools/blob/main/docs/development/index.rst#development-on-setuptools

This document assumes the reader has some passing familiarity with
using setuptools, the pkg_resources module, and pip.
[...]
as all of these subjects are
covered at length in the setuptools developer's guide and the
pkg_resources reference manual.

https://github.com/pypa/setuptools/blob/main/docs/references/keywords.rst#user-content-keyword-namespace-packages

The namespace_packages implementation relies on pkg_resources. However, pkg_resources has some undesirable behaviours,

https://github.com/pypa/setuptools/blob/main/docs/userguide/distribution.rst#specifying-your-projects-version

If you want to be certain that your chosen numbering scheme works the way
you think it will, you can use the pkg_resources.parse_version() function
to compare different version numbers::

https://github.com/pypa/setuptools/blob/main/docs/userguide/extension.rst#adding-new-egg-info-files

Some extensible applications or frameworks may want to allow third parties to
develop plugins with application or framework-specific metadata included in
the plugins' EGG-INFO directory, for easy access via the pkg_resources
metadata API.

https://github.com/pypa/setuptools/blob/main/docs/userguide/package_discovery.rst#legacy-namespace-packages

Historically, there were two methods to create namespace packages. [...]

The historical mention of setuptools + pkgutils can stay. But I'm not sure if it should still give the full example on using them. At least it should be clarified that this is not only deprecated, but no longer supported at all. Either way pkg_resource is a typo and missing s

https://github.com/pypa/setuptools/blob/main/docs/userguide/development_mode.rst#limitations Not sure about this one. Maybe it could be rephrased ?

Editable installations may not work with
:doc:namespaces created with pkgutil or pkg_resources <PyPUG:guides/packaging-namespace-packages>.
Please use :pep:420-style implicit namespaces [#namespaces]_.

https://github.com/pypa/setuptools/blob/main/docs/userguide/pyproject_config.rst#setuptools-specific-configuration

Obsolete - only relevant for pkg_resources, [...]

https://github.com/pypa/setuptools/blob/main/setuptools/dist.py

install_requires' -- a string or sequence of strings specifying project
versions that the distribution requires when installed, in the format
used by 'pkg_resources.require()'

Additional notes (not in scope of this PR): #5007 (comment)

Thanks @Avasam. I am tempted to create a new issue with your whole comment and split it up with follow up(s) PR(s) -- just because in this moment I want the info to get out there (and it will take me time to iterate over all the points you suggested).

Also, any further suggestion to improve the text can be revisited in a later PR.